In this folder are two alternate OpenDoc Libraries folders, one for 68K, one for PPC, containing a build of OpenDoc 1.0 with a lot of debugging features enabled. (Technically speaking, it's built with the ODDebug symbol defined as 1 instead of 0.) Using this build instead of the regular one can help you track down errors in your code, or, good heavens, in OpenDoc itself, and also just help you figure out the flow of control of OpenDoc. On the downside, these libraries are larger, slower, and use more memory due to the extra debugging features. Moreover, the debug build is not officially supported.
INSTALLATION
0. First install the regular build of OpenDoc using the Installer.
1. Open your Extensions folder. Now open the OpenDoc Libraries folder. Move the three shared libraries Memory Manager, OpenDocLib and OpenDoc System Data somewhere else on your disk, outside the System folder. (You could just trash them, but then you wouldn't be able to go back to the regular OpenDoc configuration without re-installing.)
2. Open the "68K Debug OpenDoc" or "PPC Debug OpenDoc" folder inside this Debug Build folder, depending on whether you are installing onto a 68K or PowerPC Macintosh.
3. Drag the contents of the folder therein to the "OpenDoc Libraries" folder in your Extensions folder.
The next steps install the debug version of Editor Setup. This isn't really necessary unless you think you've found a bug in Editor Setup itself...
4. Open the "Editors" folder in your System folder, and move the "OpenDoc Editor Setup" library elsewhere for safekeeping, somewhere outside the System folder.
6. Copy the "OpenDoc Editor Setup" library in the "Editors" folder inside the "Debug OpenDoc" folder into your Editors folder.
RESTORING THE REGULAR BUILD
1. Open your Extensions folder. Open the "OpenDoc Libraries" folder. Move the debug versions of the three shared libraries Memory Manager, OpenDocLib and OpenDoc System Data somewhere else on your disk, outside the System folder. You could even trash them, since there are copies on this CD.
2. Find the regular OpenDoc Libraries that you moved out of the way in step 1 of the installation process (above). Move them back into your Extensions:OpenDoc Libraries folder.
3. If you installed the debug Editor Setup library, remove it from the Editors folder and restore the original.
DETECTING WHICH BUILD IS INSTALLED
If you get confused and forget which build is installed, you can go to the OpenDoc Libraries folder and open the Get Info window of any of the libraries. Next to the icon, the line below the filename will include "(debug)" as part of the version name if the library is a debug version.
You could also open any OpenDoc document and see if there is an "ODDebug" sub-menu below the About command in the Apple menu (see below.)
DEBUGGING FEATURES
• The 68K build includes MacsBug symbols, and the PPC build includes traceback tables. Both of these allow debuggers to associate function names with code. MacsBug 6.5d12 or later will show function names in disassemblies and in "sc7" stack crawls. High level debuggers will also show these names in stack crawls. (Versions 1.2 — 1.3 of the Metrowerks PPC debugger will not show tracebacks, but 1.3.1 does.)
• OpenDoc's source code includes WARN and ASSERT statements that are enabled in debug builds. These will produce debugging output via DebugStr if things go wrong. You may get warnings about illegal parameters to methods, bad reference-counting, and more. This should help track down errors in your parts.
• The debug build of OpenDoc's memory manager does a lot of sanity checking on parameters passed to it, particularly bad pointers. It also fills blocks with hex "BBBB" when they are created, and "DDDD" after they're disposed, to help track down errors where you reference storage that's either uninitialized or disposed. Memory blocks are also padded with special patterns (ascii "PPPP" before a block, "SSSS" after) to detect code that writes past the bounds of a memory block and to make it easy to see the bounds of blocks while you're debugging. It's also possible to turn on a Heap Checking mode that is very slow but will detect a damaged heap almost immediately after the damage occurs. (See the “Memory Block Structure” document for details.)
• There is a sub-menu called "ODDebug" beneath the About... command in the Apple menu, containing a variety of debugging commands. See the read-me file for this menu, in the same folder as the read-me you're reading now.
• SOMTrace is enabled in OpenDoc itself. If you turn this on (probably via the ODDebug menu) all calls to OpenDoc methods will be logged to standard output. This is helpful in determining the flow of control.
CONCLUSION
We hope you find the debug build useful. We ourselves use it heavily, not only for debugging OpenDoc itself, but also for building and testing part editors. If you think you've found a bug in OpenDoc, try to reproduce it using the debug build. While this build isn't officially supported, the extra checks in the code may detect the problem sooner and provide a better notification of what's going wrong. This will help us in trying to track down and fix the bug.
